
/*
 * Copyright 2002-2015 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2015原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.config;

import org.springframework.lang.Nullable;

/**
 * Interface that defines a registry for shared bean instances.
 * Can be implemented by {@link org.springframework.beans.factory.BeanFactory}
 * implementations in order to expose their singleton management facility
 * in a uniform manner.
 *
 * <p>The {@link ConfigurableBeanFactory} interface extends this interface.
 *
 * @author Juergen Hoeller
 * @since 2.0
 * @see ConfigurableBeanFactory
 * @see org.springframework.beans.factory.support.DefaultSingletonBeanRegistry
 * @see org.springframework.beans.factory.support.AbstractBeanFactory
 */
/**
 *为共享bean实例定义注册表的接口。
 *可以通过｛@linkorg.springframework.beans.factory.BeanFactory｝实现
 *实现，以便公开其单例管理工具
 *以统一的方式。
 *
 *＜p＞｛@link ConfigurationBeanFactory｝接口扩展了此接口。
 *
 *@作者Juergen Hoeller
 *@自2.0起
 *@参见可配置的BeanFactory
 *@参见org.springframework.beans.factory.support.DefaultSingletonBeanRegistry
 *@参见org.springframework.beans.factory.support.AbstractBeanFactory
 */
public interface SingletonBeanRegistry {

	/**
	 * Register the given existing object as singleton in the bean registry,
	 * under the given bean name.
	 * <p>The given instance is supposed to be fully initialized; the registry
	 * will not perform any initialization callbacks (in particular, it won't
	 * call InitializingBean's {@code afterPropertiesSet} method).
	 * The given instance will not receive any destruction callbacks
	 * (like DisposableBean's {@code destroy} method) either.
	 * <p>When running within a full BeanFactory: <b>Register a bean definition
	 * instead of an existing instance if your bean is supposed to receive
	 * initialization and/or destruction callbacks.</b>
	 * <p>Typically invoked during registry configuration, but can also be used
	 * for runtime registration of singletons. As a consequence, a registry
	 * implementation should synchronize singleton access; it will have to do
	 * this anyway if it supports a BeanFactory's lazy initialization of singletons.
	 * @param beanName the name of the bean
	 * @param singletonObject the existing singleton object
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 * @see org.springframework.beans.factory.DisposableBean#destroy
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#registerBeanDefinition
	 */
	/**
	 *在bean注册表中将给定的现有对象注册为singleton，
	 *在给定的bean名称下。
	 *＜p＞给定实例应该完全初始化；注册表
	 *不会执行任何初始化回调（特别是，它不会
	 *调用InitializingBean的｛@code afterPropertiesSet｝方法）。
	 *给定实例将不会收到任何销毁回调
	 *（如DisposableBean的｛@code destroy｝方法）。
	 *＜p＞在完整的BeanFactory中运行时：＜b＞注册bean定义
	 *如果您的bean应该接收
	 *初始化和/或销毁回调</b>
	 *＜p＞通常在注册表配置期间调用，但也可以使用
	 *用于单体的运行时注册。因此，注册表
	 *实现应同步单例访问；这是必须的
	 *不管怎样，如果它支持BeanFactory对单例的惰性初始化，那么就应该这样做。
	 *@param beanName bean的名称
	 *@param singletonObject现有的singleton对象
	 *@see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 *@see org.springframework.beans.factory.DisposableBean#destroy
	 *@see org.springframework.beans.factory.support.BeanDefinitionRegistry#registerBeanDefinition
	 */
	void registerSingleton(String beanName, Object singletonObject);

	/**
	 * Return the (raw) singleton object registered under the given name.
	 * <p>Only checks already instantiated singletons; does not return an Object
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to access manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to access a singleton
	 * defined by a bean definition that already been created, in a raw fashion.
	 * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
	 * You need to resolve the canonical bean name first before obtaining the singleton instance.
	 * @param beanName the name of the bean to look for
	 * @return the registered singleton object, or {@code null} if none found
	 * @see ConfigurableListableBeanFactory#getBeanDefinition
	 */
	/**
	 *返回以给定名称注册的（原始）单例对象。
	 *＜p＞仅检查已实例化的单体；不返回对象
	 *对于尚未实例化的单例bean定义。
	 *＜p＞此方法的主要目的是访问手动注册的单体
	 *（请参阅｛@link#registerSingleton｝）。也可用于访问单例
	 *由已经创建的bean定义以原始方式定义。
	 *<p><b>注意：</b>此查找方法不知道FactoryBean前缀或别名。
	 *在获取单例实例之前，需要首先解析规范bean名称。
	 *@param beanName要查找的bean的名称
	 *@返回注册的单例对象，如果未找到，则返回｛@code null｝
	 *@see ConfigurationListableBeanFactory#getBeanDefinition
	 */
	@Nullable
	Object getSingleton(String beanName);

	/**
	 * Check if this registry contains a singleton instance with the given name.
	 * <p>Only checks already instantiated singletons; does not return {@code true}
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to check whether a
	 * singleton defined by a bean definition has already been created.
	 * <p>To check whether a bean factory contains a bean definition with a given name,
	 * use ListableBeanFactory's {@code containsBeanDefinition}. Calling both
	 * {@code containsBeanDefinition} and {@code containsSingleton} answers
	 * whether a specific bean factory contains a local bean instance with the given name.
	 * <p>Use BeanFactory's {@code containsBean} for general checks whether the
	 * factory knows about a bean with a given name (whether manually registered singleton
	 * instance or created by bean definition), also checking ancestor factories.
	 * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
	 * You need to resolve the canonical bean name first before checking the singleton status.
	 * @param beanName the name of the bean to look for
	 * @return if this bean factory contains a singleton instance with the given name
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.ListableBeanFactory#containsBeanDefinition
	 * @see org.springframework.beans.factory.BeanFactory#containsBean
	 */
	/**
	 *检查此注册表是否包含具有给定名称的单实例。
	 *＜p＞仅检查已实例化的单体；不返回｛@code true｝
	 *对于尚未实例化的单例bean定义。
	 *＜p＞此方法的主要目的是检查手动注册的单身者
	 *（请参阅｛@link#registerSingleton｝）。也可用于检查
	 *已经创建了由bean定义定义的singleton。
	 *＜p＞要检查bean工厂是否包含具有给定名称的bean定义，
	 *使用ListableBeanFactory的｛@code containsBeanDefinition｝。同时调用两者
	 *｛@code containsBeanDefinition｝和｛@ccode containsSingleton｝答案
	 *特定bean工厂是否包含具有给定名称的本地bean实例。
	 *＜p＞使用BeanFactory的｛@code containsBean｝进行常规检查
	 *工厂知道具有给定名称的bean（无论是手动注册的singleton
	 *实例或由bean定义创建），同时检查祖先工厂。
	 *<p><b>注意：</b>此查找方法不知道FactoryBean前缀或别名。
	 *在检查单例状态之前，需要首先解析规范bean名称。
	 *@param beanName要查找的bean的名称
	 *如果此bean工厂包含具有给定名称的单实例，则返回@return
	 *@参见#registerSingleton
	 *@see org.springframework.beans.factory.ListableBeanFactory#containsBeanDefinition
	 *@see org.springframework.beans.factory.BeanFactory#containsBean
	 */
	boolean containsSingleton(String beanName);

	/**
	 * Return the names of singleton beans registered in this registry.
	 * <p>Only checks already instantiated singletons; does not return names
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to check which singletons
	 * defined by a bean definition have already been created.
	 * @return the list of names as a String array (never {@code null})
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionNames
	 * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionNames
	 */
	/**
	 *返回在此注册表中注册的单例bean的名称。
	 *＜p＞仅检查已实例化的单体；不返回名称
	 *对于尚未实例化的单例bean定义。
	 *＜p＞此方法的主要目的是检查手动注册的单身者
	 *（请参阅｛@link#registerSingleton｝）。也可用于检查哪些单件
	 *已经创建了由bean定义定义的。
	 *@将名称列表作为字符串数组返回（从不｛@code null｝）
	 *@参见#registerSingleton
	 *@see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionNames
	 *@see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionNames
	 */
	String[] getSingletonNames();

	/**
	 * Return the number of singleton beans registered in this registry.
	 * <p>Only checks already instantiated singletons; does not count
	 * singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to count the number of
	 * singletons defined by a bean definition that have already been created.
	 * @return the number of singleton beans
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionCount
	 * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionCount
	 */
	/**
	 *返回在此注册表中注册的单例bean的数量。
	 *＜p＞仅检查已实例化的单体；不算在内
	 *尚未实例化的单例bean定义。
	 *＜p＞此方法的主要目的是检查手动注册的单身者
	 *（请参阅｛@link#registerSingleton｝）。也可用于计算
	 *由已经创建的bean定义定义的单体。
	 *@返回单例bean的数量
	 *@参见#registerSingleton
	 *@see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionCount
	 *@see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionCount
	 */
	int getSingletonCount();

	/**
	 * Return the singleton mutex used by this registry (for external collaborators).
	 * @return the mutex object (never {@code null})
	 * @since 4.2
	 */
	/**
	 *返回此注册表使用的单体互斥体（用于外部合作者）。
	 *@返回互斥对象（从不｛@code null｝）
	 *@自4.2
	 */
	Object getSingletonMutex();

}
